Security Controls
This page provides security standards for API consumers.
Introduction
This document describes, a the security controls that a consumer of HA API’s must be able to comply with in order to consume those services.
This document does not cover development standards such as OWASP that would apply to internal API developers, nor does it attempt to prescribe any standards for external API consumers for the development of software.
This document does not cover commercial and contractual requirements.
Security Controls
The following security controls are built into all of our API’s and as such become mandatory controls that a consumer MUST adhere to
Connection
- All consumers MUST connect to an endpoint made available to them as part of the on-boarding process. This endpoint will be via the MuleSoft Anypoint Cloud. Consumers may not connect to any other endpoint.
- All connections to an API end-point will be by way of an HTTPS connection with the properties as below:
Minimum TLS Version: TLS 1.2
Allowed TLS Ciphers: TLS_RSA_WITH_AES_256_CBC_SHA256,TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384,TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384,TLS_DHE_RSA_WITH_AES_256_GCM_SHA384,
TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384,TLS_ECDHE_ECDSA_WITH_AES_256_CBC_SHA384- Consumers MUST come from a Static IP Address. For fault tolerance and DR purposes, multiple individual IP addresses may be specified, however IP address ranges are not allowed.Please Note: Te Whatu Ora Northern Region reserves the right to decide what is a correct amount of IP Addresses for DR purposes. Breaches of the policy will generate the following http response code: 403 - IP is rejected
Rate Limiting
To protect our infrastructure and maximise uptime, all consumers have a rate limiting policy applied to them.
The mechanism of the policy is architected such that different consumers can have different rate limits. This provides flexibility for different use cases to be realised, and also that some consumers will be "busier" than others.
To assist with development and fault finding, our gateway has been configured to return the following headers (please note, below has been seeded with example data):
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 14
X-RateLimit-Reset: 19100
So for the example headers above, the response tells consumenrs that within the next 19100 milliseconds, only 14 more requests are allowed by the rate limiting policy, which is set to allow 20 within this time-window.
Breaches of the Policy will generate the following http response code: 429 Quota exceeded; requests blocked until the current window finishes.
Data Validation
Similar to our rate limiting control above, to protect our infrastructure all XML and JSON data is validated by XML and JSON threat protection policies in Cloudhub.
These policies ensure that the structured data is well-formed, not recursive or overly nested, and adheres to size limits specified for the fields within the structure.
Breaches of the Policy will generate the following http response code: 400 Bad Request
Authentication and Authorisation
All API's made available for consumption utilise OAUTH 2.0 and all consuming systems are required to provide a client_id and client_secret as part of the OAUTH client credential grant.
These credentials represent the individual consumer only and must not be shared with other consuming applications
Secure Transport of claims.
To ensure that claims can be securely transmitted between consumers and API's, a custom JWT token is required to be delivered with all requests.
This token is outlined as:
- Name: x-ha-metadata
- Type: JWS (Signed JWT)
- Algorithm: HMACs-SHA384
- Example JWT Header: {"alg": "HS384","typ": "JWT"}
Please note: You should have received the signing key as part of the on-boarding process. If not, please email integration-dev-team@healthalliance.co.nz
Logging and Monitoring
All consumer activity on our API Gateway is logged.
All consumers as part of the x-ha-metatdata JWT token outlined above, MUST provide the following claims:
.--------------------.---------------------------------------------------------------------------------------------------.----------------------------------.
| Metadata_parameter | Description | Example |
:--------------------+---------------------------------------------------------------------------------------------------+----------------------------------:
| Caller_id | Client authenticated user id | jblogs |
:--------------------+---------------------------------------------------------------------------------------------------+----------------------------------:
| cpn | Common Person Number | 1234 |
:--------------------+---------------------------------------------------------------------------------------------------+----------------------------------:
| consumer |Client Application Consumer name | HopkinsSoft EData Client |
:--------------------+---------------------------------------------------------------------------------------------------+----------------------------------:
| transaction_id | GUID that can be used to uniquely identify calls. | 5713577507d044f788f32a10252c9c67 |
:--------------------+---------------------------------------------------------------------------------------------------+----------------------------------:
| exp | Expiry date-time as Epoch long | 1660688350 |
:--------------------+---------------------------------------------------------------------------------------------------+----------------------------------:
| nbf | Not Before date-time as Epoch long, on or after the creation time | 1660678350 |
'--------------------'---------------------------------------------------------------------------------------------------'----------------------------------'
{
"caller_id":"jblogs",
"cpn": "1234"
"consumer":"HopkinsSoft EData Client",
"transaction_id":"5713577507d044f788f32a10252c9c67",
"exp": "1660688350",
"bnf": "1660678350"
}Additional Logging considerations
Consuming systems must be able to audit calls to the API made by their users and systems.
In anticipation of there being a need to assist HA to investigate an incident the following information should be included in Consumer logging mechanisms
· Date & Time of an API request where the time is synchronized to an external time source
· Identity of calling user
· Parameters supplied to the API call.